Chip 1996 October

home *** CD-ROM | disk | FTP | other *** search

/ Chip 1996 October / CHIP Ekim 1996.iso / prog / ter400 / tlan_001.exe / PRSCRIPT.HLP < prev next >

Wrap

Text File | 1996-04-19 | 51.9 KB | 1,630 lines

^hPreScription, The Terminate Programming Language^n IN NO EVENT WILL STRATHRORY SYSTEMS LIMITED, SERWIZ COMM OR ASSOCIATES BE LIABLE TO YOU FOR ADDITIONAL DAMAGES, INCLUDING ANY LOST PROFITS, LOST SAVINGS, OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE PRESCRIPTION OR SCRIPTS FOR PRESCRIPTION, EVEN IF WE HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Terminate has an extended script programming language. It is not only designed for logging onto a system and downloading a mail package, it has been designed with a wider view in mind. As usual Terminate throws up the ball and gives you loads of options, however if you want additional commands you cannot write yourself, then just contact us and we will try to include your suggestions. If you have never done any programming before it might be a little difficult to start out without prober guidance, however we have included various simple examples which will help you get started more easily. If you do not know what programming means, perhaps learning this simple, but yet powerful language can get you hook on the idea. You will not need this language unless you have special needs that Terminate cannot solve. BUT please be aware when you start programming. Anything is possible. That means that any possible error is also possible, and as Murphy's law describes, if anything can go wrong it will go wrong. So please do not blame us if something does goes wrong. ^hWhat can a script do for me ?^n A script can do many things. First of all it can automate some of your daily needs. Many would use a script language for getting onto a system and uploading and downloading mail packages or perhaps to check if there is a new filelist and download it. There are really many more things you can do easily. ^hCompiling scripts^n Before running a script Terminate will automatically detect if it has been compiled and will compile it if necessary. The source code is in files with the extension .TSL and the compiled ready to run script is the .TSC file. It is possible to run .TSC files without having the source code. Just access the Alt-G script menu or call Terminate with the command line /SCRIPT:script to start a script. ^hInclude files^n The Include command enables you to put certain functions into smaller files or libraries if you like. Just remember that the entire contents are put into the finished compiled script. Include SCREEN.INC Will include the source code library called SCREEN.INC. ^hLanguage syntax^n You can enter all commands or system variables in both upper, lower or mixed case. PRS will upper case everything while compiling, which means you could both enter the command "Print" or "PRINT". PRS will only keep the case of strings inside the " signs. WriteStr x,1, "Hello" would be translated to WRITESTR X,1,"Hello" If you make an error somewhere in your code you will be told at which line the error occurred. However runtime errors will only be shown at the time the error occurs. For example division by zero will make your program abort. ^hComment lines^n Comment lines are used to make the source code more easily understood the next time you or somebody else have to add or change something. You could almost say the more comment lines the better, since they are not compiled into the finished module and therefore do not take up any memory. A comment can either be the only thing on the line or after a command and must start with a % sign. Example: % This is a comment line only. Set Turbo = "ON" % Everything after here is comments. As a special compiler command you can use the "Comment". In this way you can insert comments that can later be retrieved. To insert your own copyright lines you could do: Comment "The Terminate PreScription demonstration script" Comment "This script is (Freeware) 1995 by Bo Bendtsen" You can use 5 Comment lines each of 50 characters. ^hProgram structure^n A program consists of functions and variables. You can have as many functions as you like and in any order you like. Making a structured program can increase speed and make it easier to change. You do not need to have functions or variables, you can simply use commands that are built in. You can start immediately without any definitions or strange syntaxes. One of the smallest scripts you can make could be one single line like this: Print "Hello world" ^hVariables^n A simple programming language first of all needs variables. A variable is like variable X and Y you perhaps learned about in school. It simply means a given identifier can be assigned a value. With PreScription hereafter always mentioned as "PRS" you have two kinds of variables called numbers and strings. The limit on variables is 16000 but you will probably never need that many or you will run out of memory first and it is always considered best to use as few variables as possible. All variables are global variables which can be accessed from all parts of the script. The syntax of a variable name is simple. It must begin with a letter from A to Z and then can be followed by A-Z,0-9,_. Valid names: Apple Computer X X49 Cool_5_dude Invalid names: 25XX *Hello* _NotMe ^hNumbers^n PRS uses something called floating point numbers. These numbers are limited to 2.9e-39..1.7e38 which are very very large numbers, so you should never be concerned about using too many decimals. Please note that all decimal number must use dot (.) and not comma (,) The numbers are used for storing information and for calculating, here are a few examples that might help you understand better. Identifier Value | | Set Apples = 5 The variable called Apples now has the value 5. If someone eats one of the apples you can calculate: Set Apples = Apples - 1 You now have 4 apples. Another example to calculate how much discount you got on your new modem Set NewModem = 495 Set Discount = 0.15 Set NewModem = NewModem * Discount The result in NewModem would now be 74.25 ^hStrings^n Strings are characters after each other and could look like this: "This is a string" The " signs are to tell PRS when the string starts and stops. A string can be up to 255 characters long and can have any value from ASCII 0 to ASCII 255. Some examples: Set Part1 = "A Terminate " Set Part2 = "a day keeps the doctor away" Set Joke = Part1 + Part2 To manipulate the strings there are many commands described later in this document, please look at the examples and see how some of them work. ^hExpressions and operators^n An expression is made out of operators and constants or variables. An expression could look like this: 80186 + (301 - 1) Carrier = "ON" 28800 / 2400 * 12 X = 500 < Y The operators PRS understands: + Addition < Less than - Subtraction > Greater than * Multiplication = Equal to / Division <> Not equal to \ Mod (remainder) <= Less than or equal to ^ Power >= Greater than or equal to & And | Or ! Not The various operators have different priorities in order to determine which ones to process first. Unary operators ! Multiplying operators * \ / & ^ Adding operators + - | Relational operators = <> < > <= >= If you want different priorities just use the parentheses () 20 - 2 * 5 = 10 * is higher than - (20 - 2) * 5 = 90 () is higher than any operator. ^hUser defined functions^n Creating your own functions is useful when you do the same thing over and over again or simply want a more structured program. A function is completely user defined and can contain either built-in commands or calls to other functions you have made. Function CountTo100() Set X=1 Repeat GotoXY 1,1 Print x Set X=X+1 Until X>100 EndFunc This simple function does nothing other than count to 100 on the top left corner of your screen. You call the function by entering CountTo100() To send variables to a function you need to include the variable name in the parentheses () like this: Function CountMore(HowMany) Set X=1 Repeat GotoXY 1,1 Print x Set X=X+1 Until X>HowMany EndFunc Now you can count to as many as you like. Enter: CountMore(50) And the function will count to 50. The harder part with understanding functions is to see how it can be used to return results. Here is an easy example. Function HappyHour(Drinks) Set ExtraDrinks = Drinks * 2 EndFunc ExtraDrinks To call the function you need to display or store the return value. To display you could: PrintLn "Normal hours I get ",5," drinks" PrintLn "When it is happy hour I get ",HappyHour(5)," drinks" If you want to store the result in another variable use the following: Set DrinkResult = HappyHour(5) A function can also return a value directly. Whatever is on the EndFunc line will be returned as the result. Function names follow the same rules as variable names and must at least end with () if no parameter is used. IMPORTANT: A function must be defined before it is called. ^hStatements^n PRS supports many basic statements which will be explained below. ^hIf Else Endif^n The If statement is used for evaluating an expression. You can use it for testing if certain variables have a certain value like this: Set Apples = 6 If Apples > 5 Print "Plenty left" Endif Since Apples is 6 you will see Plenty left printed on the screen. If you set Apples = 5 or less then everything will be skipped until the Endif. An If statement must always end with an Endif command, which tells PRS that the statement stops here. The Else statement means what it says. If the If statement is false the Else statement will be used. Set Apples = 4 If Apples > 5 Print "Plenty left" Else Print "Please buy more" Endif Now Apples is 4 which makes the If statement false and you will see Please buy more on your screen. ^hGoto Labels^n The Goto command is used to jump to other locations in your script. You will need to define a label which uses the following format :LabelName The label follow the same rules as variable names and must start with a colon : Some examples: :Start :End The Goto command syntax: Goto LabelName :Start PrintLn "Start" Goto JumpJump PrintLn "NeverMe" :JumpJump PrintLn "Finished" PrintLn "NeverMe" will then be skipped. Goto command should be avoided as much as possible since it creates unstructured programs. Only use for simple small programs. ^hGosub Labels Return^n Gosub commands are almost the same as Functions except that you cannot send any variables or get any results back. It simply carries out a single task and returns to the previous location. If,for example, you have a menu you want to display from several places in your script using the Gosub command could save you having the same menu twice. However it is recommended to use functions which are more flexible. The Return command tells PRS to return to the next line following the Gosub. Goto Main :Menu PrintLn "Start" Return PrintLn "NeverMe" :Main Gosub Menu ^hLoops^n Loop statements are using for repeating the same commands a variable number of times, until something is true or something is false. ^hFor Next^n For is used for performing the same commands a defined number of times. For has 4 parameters that have to be given. For Variable,Start,End,Increase The variable is a normal variable. Start is the starting value. End is the ending value Increase is the value to be increased after every Next command. When Counter is equal to the ending value the script will proceed. For Counter,1,10,1 PrintLn Counter Next Will display the numbers 1 - 10 For Counter,10,1,-1 PrintLn Counter Next Will display the numbers 10 - 1 ^hWhile EndWhile^n This loop continues until the statement is false. In other words while the statement is true all commands until the EndWhile will be executed. Set Counter = 10 While Counter <= 20 PrintLn Counter Set Counter = Counter + 1 EndWhile This will print out the numbers 10-20 ^hRepeat Until^n Repeat is much like While except that Repeat continues until the statement is true. Set Counter = 20 Repeat PrintLn Counter Set Counter = Counter - 1 Until Counter < 10 This will also print out the numbers 20-10 ^hStopping a script SHIFT-ESC, K^n If your script goes into an endless loop, you can force or at least try to stop it by first pressing Shift-Esc and then K for Kill. ^hBuilt-in commands and functions^n In addition to your own variables you can use and change certain pre-defined variables. A system function can, for example, tell you how much memory you have left (FREEMEM). A system variable could be ATTR which holds the current color attribute and which you can change as you like. A command is just like a system function except that it does not return anything. In the following section of the manual you will find 3 things: System commands = Executes a command only, no value returned (Command) System functions = Executes command and returns value (Function) System variables = Like a normal variable which can be changed (Variable) Please note that all system variables are changed for the entire Terminate, so be careful and if you change something, remember to set it back to the original value afterwards. Please note the () which will be mentioned for each description. ^hScreen, sound handling^n ^hAttr^n (Variable) Purpose: Current screen color attribute byte. Use the T-COLOR.EXE or the color selector inside Terminate to find the colors you need. Returns: 0-255 Example: Set Attr = 14 Set screen attribute to yellow Set Color = Attr Save the current attribute in variable ^hAttrBlock^n (Command) Purpose: Fills an area on the screen with a certain attribute Syntax : AttrBlock x1,y1,x2,y2,attribute Example: AttrBlock 1,2,70,20,10 Fill area (1,2)-(70,20) with color attribute light green ^hBox^n (Command) Purpose: Make a textbox on the screen using boxtypes and attributes Syntax : Box x1,y1,x2,y2,attribute,boxtype boxtype: 0=Blank, 1=Single, 2=Double, 3=Double top+single side, 4=Double side+single top, 5=* and -|, 6=Single top only, 7=Double top only Example: Box 1,1,80,25,23,1 Draw a box on the screen using single boxes and gray on blue. Notes : Attribute is same format as the Attr variable ^hCharBlock^n (Command) Purpose: Draws a block of the same character using default attribute Syntax : CharBlock x1,y1,x2,y2,character Example: CharBlock 1,1,80,25,"*" Fills the entire screen with the * character ^hClearScreen^n (Command) Purpose: Clears the entire screen, using the current attribute Syntax : ClearScreen ^hCursor^n (Command) Purpose: Cursor control Syntax : Cursor cursortype cursortype: 0 = Off, 1 = On, 2 = Max Example: Cursor 0 Turns cursor off ^hFillBlock^n (Command) Purpose: Fill an area on the screen, with an attribute and a character Syntax : FillBlock x1,y1,x2,y2,attribute,character Example: FillBlock 2,2,79,24,3,"#" Fills the area (2,2)-(79,24) with # in the cyan color ^hGetAttrXY^n (Function) Purpose: Returns attribute byte from screen on location x,y Syntax : GetAttrXY(x,y) Example: Set SaveColor = GetAttrXY 79,5 Sets SaveColor to the color of 79,5 on the screen ^hGetCharXY^n (Function) Purpose: Returns the character from screen on location x,y Syntax : GetCharXY(x,y) Example: Set SaveChar = GetCharXY 1,1 Sets SaveChar to the character of position 1,1 on the screen ^hGotoXY^n (Command) Purpose: Move cursor to location x,y Syntax : GotoXY x,y Example: GotoXY 40,12 Goto the middle of the screen ^hInWindow^n (Variable) Purpose: Use Window offset for certain screen commands Returns: 0 or 1 Example: Set InWindow=0 Current window offset not used Set InWindow=1 Current window offset used Does not work for Print, PrintLn, GotoXY ^hMouse^n (Command) Purpose: Turn on/off the mouse Syntax : Mouse action action: 0=Off, 1=On Example: Mouse 1 Turns on mouse ^hMouseDetected^n (Functions) Purpose: Report if a mouse driver was detected Syntax : MouseDetected Returns: 0=No, 1=Yes Example: If MouseDetected=1 ^hMouseGotoXY^n (Command) Purpose: Sets mouse to X,Y on the screen Syntax : MouseGotoXY x,y Example: MouseGotoXY 1,1 Move mouse to top left corner ^hMouseLeft^n (Functions) Purpose: Report if the left button was pressed Syntax : MouseLeft Returns: 0=No, 1=Yes Example: If MouseLeft=1 ^hMouseRight^n (Functions) Purpose: Report if the right button was pressed Syntax : MouseRight Returns: 0=No, 1=Yes Example: If MouseRight=1 ^hMouseWindow^n (Command) Purpose: Sets coordinates where mouse is visible Syntax : MouseWindow x1,y1,x2,y2 Example: MouseWindow 5,10,15,70 Force mouse to be inside (5,10)-(15,70) ^hMouseX^n (Functions) Purpose: Report the X position of the mouse Returns: MouseX Example: If MouseX<10 ^hMouseY^n (Functions) Purpose: Report the Y position of the mouse Syntax : MouseY Example: If MouseY>=25 ^hNoSound^n (Command) Purpose: Turn off sound soundcard or internal speaker Syntax : NoSound ^hPrint^n (Command) Purpose: Display a string on the screen at current cursor position Syntax : Print expression Example: Print "Hello world" Displays hello on the screen Print 25*10 Calculates result 250 and displays on screen ^hPrintLn^n (Command) Purpose: Display a string on the screen and press enter Syntax : PrintLn expression Example: Same command as Print except that CR+LF is added to string ^hRemoveWindow^n (Command) Purpose: Remove a window that was set by the Window command Syntax : RemoveWindow Removes top window from screen ^hScrCol^n (Variable) Purpose: Holds the number of columns on the screen (80) Returns: 40-132 Example: Print ScrCol Displays the current number of columns on screen ^hScrLen^n (Variable) Purpose: Holds the number of lines on the screen (25) Returns: 25-60 Example: Print ScrLen Displays the current number of lines on screen ^hScroll^n (Command) Purpose: Scroll a region of the screen Syntax : Scroll direction,x1,y1,x2,y2,positions,attribute direction: 0=Clear, 1=uP, 2=DOWN, 3=LEFT, 4=RIGHT a=attribute } positions are number of columns or lines to scroll attribute is the attribute to use in the cleared area Example: Scroll 4,1,1,30,5,2,7 Scroll (1,1)-(30,5) to columns to the right, clear with gray ^hSelectBar^n (Function) Purpose: The menubar selector option used in most menus in Terminate Syntax : Selectbar(y,ylen,start,attr,barx1,barx2,bartxty) Returns: 0-25 Example: Set x=SelectBar(1,3,x,113,1,20,0) Menubar starts at in the top corner of the active window or screen and is 3 lines long, starting on menuline x. Menubar is color 113 and is visible from columns 1-20. No bartext is available. Returns selection in x. 0=Esc pressed. Notes : SetBarTxt can be used to define helplines, set bartxty to the line where you want it, ScrLen is normal, 0=disable ^hSetAttr^n (Command) Purpose: Sets the current color attribute Syntax : SetAttr attribute Example: SetAttr 9 Set color to light blue ^hSetBarTxt^n (Command) Purpose: Sets helplines for SelectBar Syntax : SetBarTxt num,string Example: SetBarTxt 1,"This is helpline 1" When selectbar is in menu-position 1 this can be displayed ^hSound^n (Command) Purpose: Sound a tune using the sound card or internal speaker Syntax : Sound frequency Example: Sound 440 Set the sound to the concert pitch ^hWhereX^n (Function) Purpose: To return the current X position of the cursor Returns: 1-132 Example: Print WhereX Displays the current X position of the cursor ^hWhereY^n (Function) Purpose: To return the current Y position of the cursor Returns: 1-60 Example: Print WhereX Displays the current Y position of the cursor ^hWindow^n (Command) Purpose: Set a window and make it the current window for all functions Syntax : Window x1,y1,x2,y2,boxtype,shadow,frameattr,txtattr, headerattr,headertxt boxtype: Same as the box-command shadow : 0=no-shadow, 1=shadowtype 1, 2=shadowtype 2 Example: Window 10,1,70,10,1,1,30,23,27," Test window " Sets window at (10,1)-(70,10) using single boxes and shadowtype 1, blue background and various foreground and header as above. ^hWriteAStr^n (Command) Purpose: Display a string at position x,y and change default color Syntax : WriteAStr x,y,attribute,expression Example: WriteAStr 1,1,11,"I am light cyan" Displays the string at 1,1 in light cyan color ^hWriteAttr^n (Command) Purpose: Write a single attribute at position x,y Syntax : WriteAttr x,y,attribute Example: WriteAttr 1,1,14 Change attribute at 1,1 to yellow ^hWriteChar^n (Command) Purpose: Write a single character at x,y Syntax : WriteChar x,y,character Example: WriteChar 1,1,"X" Displays X in position 1,1 ^hWriteColorStr^n (Command) Purpose: Display a string with several colors Syntax : WriteColorStr x,y,expression Example: WriteColorStr 1,1,"^014 Yellow ^007 Gray" The ^014 means change to color 14 at this position. It is the same values as the normal attribute color. ^hWriteStr^n (Command) Purpose: Display a string at position x,y Syntax : WriteStr x,y,expression Example: WriteStr 1,1,"Hello world" Writes the string at 1,1 ^hKeyboard control^n ^hAltPressed^n (Function) Purpose: Checks if a Alternate is pressed on the keyboard Returns: 0=No, 1=Yes, Alt is being pressed Example: If AltPressed=1 ^hCtrlPressed^n (Function) Purpose: Checks if a Control is pressed on the keyboard Returns: 0=No, 1=Yes, Ctrl is being pressed Example: If CtrlPressed=1 ^hGetkey^n (Function) Purpose: Retrieves a key from the keyboard, wait if no key is ready Returns: 0-65535, value of key Example: PrintLn(GetKey) Display the value of the key pressed ^hInput^n (Function) Purpose: Input a string on screen Syntax : Input(x,y,length,textattribute,editattribute,string) Returns: String Example: Set Result=Input(1,1,40,11,3,"Input string") Inputs a string at position 1,1 with the length of 40 characters on the colors cyan and light cyan. ^hKey^n (Variable) Purpose: Hold the last keyboard code Returns: 0-65535 Example: While Key<>13 While Escape is not pressed run the loop ^hKeyPressed^n (Function) Purpose: Checks if a key has been pressed on the keyboard Returns: 0=No key ready, 1=key ready to be read by Getkey Example: While KeyPressed=0 While no key is pressed run the loop ^hShiftPressed^n (Function) Purpose: Checks if a Shift is pressed on the keyboard Returns: 0=No, 1=Yes, Shift is being pressed Example: If ShiftPressed=1 ^hWaitEnter^n (Command) Purpose: Wait until someone presses the ENTER key Syntax : WaitEnter ^hVariable manipulation^n ^hBlankAfter^n (Function) Purpose: Add spaces after a string until a specified length is obtained Example: BlankAfter(string,length) Returns: String Example: Print BlankAfter("Test",7) Displays "Test " on the screen ^hBlankBefore^n (Function) Purpose: Add spaces before a string until a specified length is obtained Example: BlankBefore(string,length) Returns: String Example: Print BlankBefore("Test",7) Displays " Test" on the screen ^hChr^n (Function) Purpose: Converts a number to the ASCII value Syntax : Chr(number) Returns: Character #0-#255 Example: Set Val=Chr(200) ^hCopy^n (Function) Purpose: Copy out part of a string Example: Copy(string,start,characters) Returns: String Example: Print Copy("Test",1,2) Displays "Te" on the screen ^hDelete^n (Function) Purpose: Delete part of string Syntax : Delete(string,index,characters) Returns: String Example: Print Delete("Hello",4,2) Displays "Hel" on screen ^hGrabword^n (Function) Purpose: Return a single word in a string Syntax : GrabWord(expression,word-number) Returns: String Example: Print GrabWord("Hello World",2) Displays "World" on screen ^hInteger^n (Function) Purpose: Cut off all decimals and returner integer Syntax : Integer(number) Returns: Integer Example: Print Integer(1.50) Prints the number 1 ^hLength^n (Function) Purpose: Return the length of a string Syntax : Length(string) Returns: 0-255 Example: Print length("test") Displays the number 4 on screen ^hNumchars^n (Function) Purpose: Return a string with a number of the same characters Syntax : Numchars(character,numbers) Returns: String Example: Print Numchars("-",5) Displays "-----" on screen ^hOrd^n (Function) Purpose: Converts an ASCII value to ordinary value Syntax : Ord(number) Returns: Character #0-#255 Example: Set Val=Ord("A") ^hParameter^n (Function) Purpose: Return command line parameter when calling script Syntax : Parameter(number) Returns: String Example: Set ComPort=Parameter(1) ^hPos^n (Function) Purpose: Search for sub-string in string Syntax : Pos(sub-string,string) Returns: 0=Not found, 1=255 position found Example: Print Pos("World","Hello World") Displays the number 6 on screen ^hRound^n (Function) Purpose: Round an real number Syntax : Round(number) Returns: Integer Example: Print Round(1.49) Prints the number 1 Print Round(1.50) Prints the number 2 ^hSet^n (Command) Purpose: Assign a value to a variable Syntax : Set variable name = value Example: Set Result = 20*10 Set Apples = "Good tasting" ^hStLocase^n (Function) Purpose: Lowercase a string Syntax : StLocase(string) Returns: String Example: Print LoUpcase("HELLO") Displays hello on screen ^hStUpcase^n (Function) Purpose: Uppercase a string Syntax : StUpcase(string) Returns: String Example: Print StUpcase("hello") Displays HELLO on screen ^hStacks and queues^n A stack is a First-In-Last-Out buffer, which can be used for saving variables or values that need to be used later. A queue is a First-In-First-Out buffer (FIFO) which can be used for buffering variables. ^hQueueLook^n (Command) Purpose: Retrieves the latest variable from the queue without popping Syntax : QueueLook variable Example: QueueLook Count Count is set to latest value pushed on queue without popping ^hQueuePop^n (Command) Purpose: Retrieve the latest variable pushed on the user-queue Syntax : QueuePop variable Example: QueuePop Count Takes the latest pushed value from queue and puts into Count ^hQueuePush^n (Command) Purpose: Pushes a variable on the user-queue to be retrieved later Syntax : QueuePush variable Example: QueuePush Count Push Count on the user-queue ^hStackLook^n (Command) Purpose: Retrieves the latest variable from the stack without popping Syntax : StackLook variable Example: StackLook Count Count is set to latest value pushed on stack without popping ^hStackPop^n (Command) Purpose: Retrieve the latest variable pushed on the user-stack Syntax : StackPop variable Example: StackPop Count Takes the latest pushed value from stack and puts into Count ^hStackPush^n (Command) Purpose: Pushes a variable on the user-stack to be retrieved later Syntax : StackPush variable Example: StackPush Count Push Count on the user-stack ^hSerial interface handling^n All commands will return a resultcode in DeviceResult, if 0 the command was executed succesfully. ^hCarrier^n (Function) Purpose: Check if the carrier is high Returns: 0=Carrier low, 1=Carrier high Example: While Carrier=1 While carrier detect is high run the loop ^hCharsWaiting^n (Function) Purpose: Get number of chars waiting in input buffer Returns: 0-65535 Example: Print "Waiting characters ",CharsWaiting ^hCloseCom^n (Command) Purpose: Close the current device Syntax : CloseCom ^hClrLastIncoming^n (Command) Purpose: Clear LastIncoming to 255 #0 Syntax : ClrLastIncoming ^hDeviceResult^n (Variable) Purpose: The last result code from the device, 0=Ok Returns: 0-65535 Example: Print "Device result ",DeviceResult ^hDeviceResultStr^n (Function) Purpose: Return error text of the last result code from the device, 0=Ok Syntax : DeviceResultStr(Resultcode) Returns: String Example: Print "Device result ",DeviceResultStr(DeviceResult) ^hFlushInBuffer^n (Command) Purpose: Flush the incoming device buffer Syntax : FlushInBuffer ^hGetBaud^n (Function) Purpose: Get the current baud rate Returns: 0-115200 Example: Print "Current baud ",GetBaud ^hGetChar^n (Function) Purpose: Get a character from the device Returns: #0..#255 Example: Print GetChar ^hGetCharTimeout^n (Function) Purpose: Get a character from the device, timeout in tics Syntax : GetCharTimeout(number-of-tics) Example: Set Received=GetCharTimeout(91) Try to get a character from the device timeout in 5 seconds Notes : A PC has 18.2 tics per second 5x18.2 = 91 tics = 5 seconds ^hGetData^n (Function) Purpose: Get the current databits Returns: 7-8 Example: Print "Current databits ",GetData ^hGetInterface^n (Function) Purpose: Get the serial interface type in use Returns: 0=NoDevice, 1=UartDevice, 2=Int 14h, 3=Fossil, 4=Digiboard Example: Print "Active serial interface type ",GetInterface ^hGetParity^n (Function) Purpose: Get the current parity in use Returns: N=None, O=Odd, E=Even, M=Mark, S=Space Example: Print "Current parity in use ",GetParity ^hGetPort^n (Function) Purpose: Get the active port number Returns: 1-8 Example: Print "Active port ",GetPort ^hGetStop^n (Function) Purpose: Get the current stopbits Returns: 1-2 Example: Print "Current stopbits ",GetStop ^hHangup^n (Command) Purpose: Drop the carrier, using the hangup string or toggling DTR Syntax : Hangup ^hInitDevice^n (Command) Purpose: Open one of the devices in Terminate Syntax : InitDevice devicenumber,port,baud Example: InitDevice 4,2,57600 Open device 4, using port 2 with baud 57600 Notes : If another device is already open it will be closed. ^hInitDirect^n (Command) Purpose: Open a device and initialise the communications port directly Syntax : InitDirect interface,port,baud,databits,stopbits,parity, inbufsize,outbufsize,flowctrl Interface : 0=NoDevice, 1=UartDevice, 2=Int 14h, 3=Fossil, 4=Digiboard Port : 1-8 Databits : 7-8 Stopbits : 1-2 Parity : N=None, O=Odd, E=Even, M=Mark, S=Space Inbufsize : 10-65000 Outbufsize: 10-65000 Flowctrl : 0=None, 1=RTS/CTS, 2=XonXoff, 3=DSR/DTR Example: InitDirect 1,2,38400,8,1,"N",1024,1024,1 Use Uart on COM2 with 38400,8N1 and 1024 bytes buffers for in/out. RTS/CTS flowcontrol Notes : If another device is already open it will be closed. ^hLastIncoming^n (Variable) Purpose: Holds the last 255 characters received by GetChar Returns: String Example: Print LastIncoming ^hSend^n (Command) Purpose: Send a string to the device with modem delay. Syntax : Send expression Example: Send "ATA^M" Send the HAYES answering command to device ^hSendRaw^n (Command) Purpose: Send a string to the device in raw format Syntax : SendRaw expression Example: Sendraw "----------------" ^hWaitFor^n (Command) Purpose: Wait for a string from device Syntax : WaitFor expression,seconds Example: WaitFor "Enter name:",20 If IOResult<>0 Goto Timeout Endif Notes : IOResult=0 Got String, IOResult=2 Timeout ^hFile handling^n All file commands will give the result code in IOResult. ^hIOResult^n (Variable) Purpose: Result of the last file operation Returns: 0-65535, 0=Ok Example: Print IOResult PRS supports two kind of files. Binary files and text files. Binary files are data files like TERMINAT.EXE which contain characters from #0..#255. Text files like AUTOEXEC.BAT are line based and easier to use. PRS allows you to have 8 open files at the same time. 4 binary files and 4 text files. ^hText files^n Textfiles are easier to understand when you see the following example: OpenText 1,"C:\AUTOEXEC.BAT",0 While EndofTextFile(1)=0 PrintLn readtext(1) EndWhile CloseText 1 This will open a text file and print the entire file on your screen. ^hCloseText^n (Command) Purpose: Close a text file Syntax : CloseText handle Example: CloseText 1 ^hEndOfTextFile^n (Function) Purpose: Tells you if we are on the last line in the file Syntax : EndofTextFile(handle) Returns: 0=No, 1=Yes, end-of-file Example: While EndofTextFile(1)=0 Continue until end-of-file ^hOpenText^n (Command) Purpose: Opens a text file for reading, writing or appending. Syntax : OpenText handle,filename,mode handle : 1-4 filename: Full pathname of file mode : 0=Read, 1=Write, 2=Append Example: OpenText 1,"C:\AUTOEXEC.BAT",0 Opens text file 1 for reading. ^hPosText^n (Function) Purpose: Report the byte position in a text file. Syntax : PosText(handle) Example: Print "Position ",PosText(1) Show the byte-position on text file 1 ^hReadText^n (Function) Purpose: Read 1 line from a text file Syntax : ReadText(handle) Returns: String Example: PrintLn ReadText(1) Reads and displays one line from text file 1 ^hSeekText^n (Command) Purpose: Seek to a file position in a text file. Syntax : SeekText handle,position Position is the byte-position in file 0=First byte Example: SeekText 1,1000 Seeks to position 1000 in the file ^hSizeText^n (Function) Purpose: Report the size in bytes on a text file Syntax : SizeText(handle) Returns: filesize-in-bytes Example: Print SizeText(handle) ^hWriteLnText^n (Command) Purpose: Write a string to a text file Syntax : WriteLnText handle,string Example: WriteLnText 1,OutString Writes the contents of OutString to text file 1 ^hWriteText^n (Command) Purpose: Write a string to a text file without CR+LF Syntax : WriteText handle,string Example: WriteText 1,OutString Writes the contents of OutString to text file 1 ^hBinary files^n ^hClose^n (Command) Purpose: Close a file Syntax : Close handle Example: Close 1 ^hEof^n (Function) Purpose: Tells you if we are on the last position in the binary file Syntax : EndofTextFile(handle) Returns: 0=No, 1=Yes, end-of-file Example: While Eof(1)=0 Continue until end-of-file ^hFilePos^n (Function) Purpose: Report the byte position in a binary file. Syntax : FilePos(handle) Example: Print "Position ",FilePos(1) Show the byte-position on binary file 1 ^hFileSize^n (Function) Purpose: Report the size in bytes on a binary file Syntax : FileSize(handle) Returns: filesize-in-bytes Example: Print FileSize(handle) ^hOpen^n (Command) Purpose: Opens a binary file for reading, writing or both. Syntax : Open handle,filename,mode,filemode handle : 1-4 filename: Full pathname of file mode : 0=Read, 1=Write, 2=Append filemode: 0=ReadOnly,1=WriteOnly,2=ReadWrite,+64=DenyNone Example: Open 1,"TERMINAT.CFG",0,0 Opens binary file 1 for reading. ^hRead^n (Function) Purpose: Reads a number of characters from a binary file Syntax : Read(handle,numbytes) Returns: String Example: Set FileGrab=Read(1,20) Read 20 characters into FileGrab ^hSeek^n (Command) Purpose: Seek to a file position in a binary file. Syntax : Seek handle,position Position is the byte-position in file 0=First byte Example: Seek 1,1000 Seeks to position 1000 in the file ^hWrite^n (Command) Purpose: Write a number of characters to a binary file Syntax : Write(1,expression) Example: Write(1,"HELLO") ^hDOS commands^n The result of each call is stored in IOResult ^hDeleteFile^n (Command) Purpose: Deletes a file Syntax : DeleteFile filename Example: DeleteFile "TERMINAT.BAK" ^hExec^n (Command) Purpose: Call a DOS command Syntax : Exec expression Example: Exec "TERMAIL\TM.EXE !M" Call the TerMail program Notes : All the !-commands described other places in the manual can be used here. !M=Swap out memory ^hFindFirst^n (Function) Purpose: Finds a file allowing wildcards Syntax : FindFirst(expression,attribute) Attribute: 1=ReadOnly, 2=Hidden, 4=System, 8=VolumeID, 16=Directory, 32=Archive, 63=AnyFile Returns: Filename only or blank if no mathces Example: Print FindFirst("C:\*.*",32) ^hFindNext^n (Command) Purpose: Find next match after a FindFirst use Returns: Filename found Example: PrintLn FindFirst("C:\*.*",32) While IOResult=0 PrintLn FindNext EndWhile Will display to entire root of your C-drive ^hFindNextSize^n (Variable) Purpose: Returns filesize of last FindNext Returns: Size in bytes Example: PrintLn FindNextSize ^hFindNextAttr^n (Variable) Purpose: Returns file attribute of last FindNext Returns: Byte Example: PrintLn FindNextAttr ^hFindNextTime^n (Variable) Purpose: Returns filetime of last FindNext Returns: Time in unix number Example: PrintLn FindNextTime ^hRename^n (Command) Purpose: Rename a file to another name Syntax : Rename filename new-filename Example: Rename "TEST.TXT","TEST2.TXT" Renames TEST.TXT -> TEST2.TXT ^hDate, time handling^n ^hGetDate^n (Variable) Purpose: Returns date in formatted form Returns: Date-string DD-Mmm-YYYY (Day, Month-string, Year) Example: PrintLn GetDate Print todays date: 7-Aug-1995, 21-Jan-96 ^hGetDateRaw^n (Variable) Purpose: Returns date in raw form Returns: String YYYY MM DD DOW (Year, Month, Day, Day-of-week) Example: PrintLn GetDateRaw Print current date: 1995 08 07 01 ^hGetTime^n (Variable) Purpose: Returns time in formatted form Returns: Time-string HH:MM:SS Example: PrintLn GetTime Print current time: 18:39:25 ^hResetTimer^n (Command) Purpose: Resets timer 1-4 Syntax : ResetTimer timer-num,seconds Example: ResetTimer 1,60 Sets timer to expire after 60 seconds ^hTimeElapsed^n (Function) Purpose: Returns in milliseconds time elapsed since ResetTimer Syntax : TimeElapsed(timer-num) Returns: Milliseconds elapsed Example: PrintLn TimeElapsed(1) ^hTimerExpired^n (Function) Purpose: Check if a timer has expired. Syntax : TimerExpired(timer-num) Returns: 0=No, 1=Timer expired Example: Until TimerExpired(1)=1 ^hWait^n (Command) Purpose: Pause in 1/100 seconds Syntax : Wait num-1/100-seconds Example: Wait 200 Wait 2 seconds before continuing ^hFile transfers^n One of the most common tasks you will need the scripts for is to transfer files to/from another system. To do this you need to use the internal or external protocols specified below. Protocols 1 + Zmodem + = Batch protocol 2 + ZedZap 3 Ascii 4 Xmodem 5 Xmodem-1K 6 Xmodem-1K-G 7 + Ymodem 8 + Ymodem-G 9 + Kermit 10 + CompuServe B+ 11..22 ? External protocols ^hDownload^n (Command) Purpose: Receive files from another system Syntax : Download protocol,filename Example: Download 1 Download 3,"CAPTURE.TXT" Notes : All protocols that are not batch must have a filename ^hUpload^n (Command) Purpose: Send files to another system Syntax : Upload protocol,filename(s)/wildcards Example: Upload 1,"C:\TERMINAT\UPLOAD\DANBBS.QWK" Upload 3,"C:\TERMINAT\UPLOAD\*.* C:\TERMINAT\DOCS\*.DOC" ^hEmulations^n ^hSetTerminal^n (Command) Purpose: Change to terminal slot Syntax : SetTerminal slot Example: SetTerminal 1 ANSI-BBS is now the current terminal ^hWriteTerminal^n (Command) Purpose: Send a string to terminal emulation Syntax : WriteTerminal expression Example: If CharsWaiting<>0 WriteTerminal GetChar Endif Displays received character from device ^hTerminate control^n ^hDial^n (Command) Purpose: Dial number in the phonebook Syntax : Dial numbers,numbers,numbers..... Example: Dial 1,2,3,4 Dial 27 Notes : IOResult=0 No connect, IOResult=1 Connection ^hGetUserName^n (Function) Purpose: Get username from phonebook record Syntax : GetUserName Returns: String Example: Send GetUserName Send username to device ^hGetUserPassword^n (Function) Purpose: Get password from phonebook record or default Syntax : GetUserPassword Returns: String Example: Send GetUserPassword Send password to device ^hMainLoop^n (Command) Purpose: Run Terminate main loop Syntax : MainLoop times Example: MainLoop 10 Allow the script to access all the Terminate functions ^hDirect hardware control^n Direct memory commands can be dangerous since it can access your hardware directly or indirectly. Please do not use any memory commands if you are the slightest bit insecure on their use. ^hFreeMem^n (Function) Purpose: How much memory is left Returns: Number of bytes available for script language Example: Print FreeMem Displays free memory on screen ^hInterrupt^n (Function) Purpose: Call any interrupt with register value *WARNING DANGEROUS* Syntax : Interrupt(interrupt-number,ax,bx,cx,dx,si,di,ds,es) Returns: String: ah al bh bl ch cl dh dl si di ds es flags Example: Print "Videomode:",GrabWord(Interrupt(16,3840,0,0,0,0,0,0,0),2) Get videomode in word 2 in string Notes : Be very careful with command. It gives you access to the complete PC and therefore one wrong call can result in the worst errors. If you are not an expirenced programmer do not under any circumstances use this command. ^hMem^n (Function) Purpose: Get a byte directly from memory location Syntax : Mem(segment,offset) Returns: 0-255 Example: Print "Memory 0:0",Mem(0,0) ^hPortIn^n (Function) Purpose: Get a byte directly from a hardware port Syntax : PortIn(port) Example: You will know if you need it! ^hPortOut^n (Command) Purpose: Send a byte to a hardware port Syntax : PortOut port,byte Example: You will know if you need it! ^hPutMem^n (Command) Purpose: Put a byte directly to memory location Syntax : PutMem byte,segment,offset Example: PutMem 65,47104,0 Notes : BE CAREFULL! ^hFax commands^n ^hSendFax^n (Command) Purpose: Send a fax to a specific telephone number Syntax : SendFax filename,number,[to-name,subject] Example: SendFax "DOCS\PROBLEM.DOC","43627178","Sysop","Problem" SendFax "C:\AUTOEXEC.BAT","43627178" Notes : Text, TIFF or PCX files will be converted to APF format first Note that the default fax settings and cover page will be used. ^hNumeric conversion^n ^hBinary^n (Function) Purpose: Returns an binary string Syntax : Binary(Integer,bits) Example: PrintLn Binary(255,8) PrintLn Binary(256,16) ^hBinToInt^n (Function) Purpose: Returns an integer from a binary string Syntax : BinToInt(string) Example: PrintLn BinToInt("11111111") ^hByteToHex^n (Function) Purpose: Returns a string with hex value of byte 8-bit Syntax : ByteToHex(Byte) Example: PrintLn ByteToHex(255) ^hHexToInteger^n (Function) Purpose: Returns an integer converted from a hex-string Syntax : HexToInteger(String) Example: PrintLn HexToInteger("FFFF") ^hLongToHex^n (Function) Purpose: Returns a string with hex value of a double word 32-bit Syntax : LongToHex(Byte) Example: PrintLn LongToHex(255) ^hWordToHex^n (Function) Purpose: Returns a string with hex value of word 16-bit Syntax : WordToHex(Byte) Example: PrintLn WordToHex(65000) ^hOther commands^n ^hExitTerminate^n (Command) Purpose: Exit the script and Terminate with errorlevel Syntax : ExitTerminal [errorlevel] Example: ExitTerminate 100 (Errorlevel 100) ExitTerminate (Errorlevel 1) ^hGetCrc^n (Function) Purpose: Update a Crc-16 checksum Syntax : GetCrc(Byte,Old-Crc) Example: Set Crc=GetCrc(X,Crc) ^hGetCrcLong^n (Function) Purpose: Update a Crc-32 checksum Syntax : GetCrcLong(Byte,Old-Crc) Example: Set Crc=GetCrcLong(X,Crc) ^hRandom^n (Function) Purpose: Get a random number between 0-65535 Syntax : Random(max) Example: Print Random(100) Displays a random number between 0-99 ^hRandomize^n (Command) Purpose: To initialise the random factor for the Random function Syntax : Randomize ^hCommentNum^n (Function) Purpose: Get number of script comments Syntax : CommentNum(0) Example: Set Comments=CommentNum(0) <- Must be zero! ^hCommentStr^n (Function) Purpose: Get script comments Syntax : CommentStr(Commentnumber) Example: PrintLn CommentStr(1) ^hTerminate^n (Command) Purpose: Exit the script Syntax : Exit